/*
 * Turdlet.java
 *
 * Created on October 21, 2006, 1:35 AM
 *
 */

package tomkitty.turdlet;

import tomkitty.server.*;
import tomkitty.util.*;
import java.io.BufferedReader;
import java.util.Hashtable;

/**
 *
 * All turdlets must implement this interface. Turdlets will run in threads
 * so it is important to make sure implementations are thread-safe. A basic
 * overview of the process of turdletification is as follows:
 *
 * <ul>
 * <li>Server <code>accepts()</code> incoming connection.</li>
 * <li>Server gets a handler thread to handle incoming connnection.</li>
 * <li>Server hands over the socket to the handler and listens for more
 *		 incoming connections.</li>
 * <li>Handler parses the request header and tries to determine which
 *		 turdlet to delegate to, based on the resource requested. For example,
 *		 if the resource <i>/MyTurdlet?foo=bar</i> is requested, then the
 *		 turdlet class MyTurdlet is instantiated. If the class can not be 
 *     found, or if some error occurs during processing then an <code>
 *		 ErrorTurdlet</code> is created and the request is delegated to it.</li>
 * <li>The <code>init</code> method of the new turdlet is called.</li>
 * <li>The <code>doit</code> method of the new turdlet is called. This is 
 *		 where the real work takes place in the turdlet.</li>
 * <li>The handler spins in a tight loop waiting for the turdlet's <code>
 *		 isDone</code> method to return <i>true</i>.
 * <li>The socket is closed and the turdlet is recycled back into the pool 
 *		 of waiting turdlets or it is destroyed.</li>
 * </ul>
 *
 * @author alan
 * @see tomkitty.turdlet.TurdletBase
 */
public interface Turdlet {
		
		/**
		 *
		 * As long as this method returns <i>false</i> the turdlet will not be 
		 * recycled or destroyed, and the buffered streams will remain open. 
		 * This is useful in case the turdlet wants to wait for an event or 
		 * something.
		 *
		 * @return <i>true</i> when finished, <i>false</i> when still processing 
		 * or waiting.
		 */
		boolean isDone();

		/**
		 *
		 * This is where the input and output streams are set up, etc. This
		 * method is called by the turdlet container after it creates a new
		 * turdlet.
		 *
		 * @param context the turdlet's context object.
		 */
    void init(TurdletContext context);

		/**
		 *
		 * This method is called by the turdlet container after it creates a new
		 * turdlet and after the new turdlet's <code>init</code> method has been 
		 * called.
		 */
    void doit();

		void setStatus(String status);

		void setContentType(String type);

		void header(String headerLine);

}
